home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Magnum One
/
Magnum One (Mid-American Digital) (Disc Manufacturing).iso
/
d1
/
burnout.arc
/
BURNOUT.DOC
< prev
next >
Wrap
Text File
|
1985-11-28
|
26KB
|
568 lines
V2.01 22-Mar-1985
Burnout II Documentation
------------------------
Function
--------
Burnout is an enhanced version of the old screen blanking
program of the same name; its primary purpose is to blank out
your video display after a specified length of time. This new
version is signifcantly enhanced over the older program; not
only does it allow you better control over its operations, but
it is written as a virtual device driver so that you can control
it directly from your own programs.
V2.01 Notes
-----------
The status report has been changed to be consistent with the
format of input parameters. The new status report is:
count,reset,B,C+,V+,H+
Note that count and reset have been reversed. This makes it
possible to reset burnout's parameters by passing its own report
back to it, beginning with the first character of the reset
count. (The "B" will be ignored because it's not a valid
parameter.)
There is also a burnout "R" command which was present but not
documented in version 2.00.
There was an error in the V2.00 documentation, in which it was
stated that you must send a "#" to BRNDEV to prepare it for a
status request. This is not correct; the "@" flush character is
sufficient. This error also cause the first BASIC demo program
in the TRICKS section to malfunction. Line 40, which was
40 PRINT #1,"@#";
should have been
40 PRINT #1,"@";
Installation
------------
To install burnout, follow two steps: place the file BURNDEV.SYS
in the root directory of your boot diskette or hard disk, and
modify the CONFIG.SYS file to include the statement
"device=burndev.sys".
In case you are not familiar with CONFIG.SYS: this is a small
text file which DOS reads when booting. It contains various
pieces of information which DOS and other programs can use when
setting themselves up. Look in the root directory of your boot
disk for the file CONFIG.SYS. If no such file exists, just
type:
copy con \config.sys<Enter>
device=burndev.sys<Enter>
Then press Ctrl-Z (you'll see "^Z") and <Enter>, and you're
done.
If you already have a CONFIG.SYS file (which is likely), you
must edit it to include the statement "device=burndev.sys". Do
this using your text editor or word processor in text mode (or
Edlin, heaven forbid). Retain all existing information, and add
the new line.
WARNING: version 2.0 is experimental. Don't install burnout on
your only bootable disk. There's always a chance something will
go wrong go wrong go wrong, and you can't delete the CONFIG.SYS
or BURNDEV.SYS files unless you can boot the machine.
Now reboot your machine. If all goes well, it will boot as
usual. There will be no indication that anything has happened.
However, the screen should blank out after about ten minutes of
inactivity.
Burnout parameters
------------------
There are several ways in which you can alter the operation of
burnout. There is a demo program called BURNOUT.COM which you
can use for this purpose. Its syntax is as follows:
burnout [count] [V+-] [H+-] [C+-]
The parameters are as follows:
COUNT: changes the number of clock ticks until the screen
blanks (this is called the "reset count"). For example,
burnout 5000
sets the reset count to 5000. This means that if burnout
observes no keyboard or video activity within 5000 clock
ticks, it will blank the screen. On the IBM PC, there are
about 18.2 ticks per second, so this means that the screen will
clear after about 5000/18.2 seconds (275 seconds, or about four
and a half minutes). (The default value on powerup is 10800
ticks, or about 10 minutes). You can set the reset count
anywhere from 1 tick (not highly recommended) to 65535 ticks
(about an hour).
If you set the reset count to 0, burnout will be effectively
"deinstalled" (equivalent to the old BURNOUT /Q) until you set a
new nonzero count. This is useful for programs that don't get
along with the screen blanker.
V: This stands for Video, and tells burnout whether you want it
to monitor video activity in adddition to keyboard activity.
You can set either "V+" (monitor video), or "V-" (don't). Thus,
burnout 5000 V-
sets the program to reset to 5000 ticks, and not to monitor
video. Why would you not want to monitor video? Primarily
because some programs continuously update the display (e.g.,
with a ticking clock) even when they're not doing anything. If
you set V+, the screen would never blank. The powerup default
setting is V+. (V- is equivalent to the old "BURNOUT /K"
command).
H: This stands for Hardware, and tells burnout whether you want
it to blank the screen by manipulating the hardware (i.e., by
turning off the video signal), or by software (which it does by
temporarily changing screen attributes to black-on-black, or
nondisplay). Some explanation is in order.
The preferred method of blanking the screen is to do it by
manipulating the PC's video controller. This method is very
fast and in general has fewer problems than the software method.
However, it does have two problems. First, it is nonportable:
it doesn't work with all PC-compatibles. Second, there have
been reports that this method can PHYSICALLY DAMAGE a few
non-IBM video adapters, notably the Hercules monochrome graphics
adapter.
DO NOT USE H+ IF YOU ARE USING A HERCULES VIDEO ADAPTER!!! YOU
HAVE BEEN WARNED!!!
If you are NOT using a Hercules card, try H+, with a setting of
about 10 seconds, to make sure it works:
burnout 180 H+
The screen should blank in about 10 seconds. If it does not,
you will have to use H- (which is the powerup default setting).
Reset burnout to some reasonable period of time, of course,
after you have tested.
C: This stands for Continuous Clear. If you are using H+, you
can skip this one, because it is ignored in hardware blanking
mode. As mentioned above, software blanking is achieved by
simply changing all video attributes to nondisplay
(black-on-black). Now, if you are running in V- mode (not
monitoring video), or if you are running a program which
achieves video output by writing data directly to screen memory,
new data will begin to appear on the screen, even though it is
blanked. Continuous Clear attempts to remedy this by simply
resetting all the attributes to black-on-black every time the
clock ticks (18 times per second). The new data will flash on
the screen and disappear immediately. Powerup default is C-.
Note that C- is equivalent to the old "BURNOUT /N" command.
The burnout parameters can be entered in any order; illegal
parameters, capitalization, and separators are ignored. Thus,
the following are all equivalent:
burnout 5000 V+ H-
burnout 5000,V+,H-
burnout v+h-5000
burnout H+, V-, 5000
burnout 5000H-V+
burnout h-5000v+
If you enter a count greater than 65535, you're on your own.
You won't get what you expect. If you don't like the way
BURNOUT.COM works, you're free to "roll your own"; see the next
section.
When BURNOUT has completed, it will display the current device
status. For example:
Status: 09994,10000, ,C-,V+,H+
The format of the status line is:
Status: nnnnn,nnnnn,B,C+-,V+-,H+-
The first number is the current number of clock ticks remaining
till the next screen blank; the second is the reset count (in
this case, the two numbers will be very close). The "B", if
present, indicates that the screen is currently Blanked (you
won't see this after running BURNOUT). The "C", "V", and "H"
flags indicate the current status of Continuous Clear, Video
monitoring, and Hardware clearing. If the parameter is active,
the indicator will be followed by a plus sign (+), otherwise a
minus sign (-). In the above example, then, the current count
is 09994, the reset count is 10000, the screen is not blanked
(naturally), Continous Clear is off, and Video monitoring and
Hardware clearing are on.
Unspecified parameters are not changed; thus, if you run burnout
without any parameters, it will simply display status without
changing anything.
You can also include any of these parameters in the config.sys
file so that they will be set immediately when you boot. For
example,
device=burndev.sys 8000 H+ V-
Burnout command
---------------
Burnout has one command, the "R" (reset) command. When the
burnout device receives an R in its input stream, it performs
two actions: it restores the screen if it is current blanked,
and it resets the current count to the reset count. The R
command's primary purpose is to allow other applications to
force a burnout device reset, as described below.
Using the BRNDEV device
-----------------------
As mentioned above, the screen blanker is implemented as a
virtual device. The advantage to this is that it can be
interrogated or controlled very easily, from the DOS command
line or from your own programs. In fact, BURNOUT.COM is a very
simple program which takes your command line parameters, sends
them to the burnout device, reads the current status back from
the device, and displays the results. This section explains how
to do this.
When DOS finds the "device=burndev.sys" line in config.sys, it
loads and installs the burndev.sys program as a virtual device.
What this means, practically speaking, is that there is now a
new "device" attached to your PC. You already have several
devices installed: CON, PRN, COM1 and COM2, AUX, your disk
drives, and possibly a RAM (or virtual) disk if you have
installed VDISK.SYS or another disk emulator.
The new device is known to DOS by the name "BRNDEV" (note: this
is NOT "BURNDEV", it's "BRNDEV", no U). Like other devices, you
can write (send information) to the device, and you can read
(receive information) from the device. BRNDEV is designed to
accept certain very specific information (the burnout
parameters) when it is written to, and to return certain very
specific information (the burnout status) when it is read from.
Writing to BRNDEV
-----------------
How do you "write" to BRNDEV? There are many ways. The
simplest is to do it right from the keyboard, at the DOS prompt:
copy con brndev<Enter>
@8000 V-#<Enter>
^Z<Enter>
The "copy con brndev" command instructs DOS that you want to
copy input from the console device to the BRNDEV device. The
console input "@5000 V-#<Enter>" is copied to the burnout device
when you hit the Ctrl-Z (end of copy) and <Enter> (execute)
keys. To prove it worked, type "burnout" and look at the new
parameters; they should reflect a reset count of 8000 and no
video monitoring. (The significance of @ and # will be
explained shortly.)
Another way to write to the device would be to copy a small
textfile to BRNDEV. As an example, type
copy con brndemo.txt<Enter>
@10000V+#<Enter>
^Z<Enter>
You should now have a small textfile, the contents of which are
"@10000V+#". To sen it to BRNDEV, just type
copy brndemo.txt brndev
or
type brndemo.txt > brndev
Run burnout to prove that the parameters have changed.
The purpose of the "@" at the beginning of the output to BRNDEV
is to tell the device to flush or rewind its I/O buffers.
BRNDEV just sees a sequence of characters coming from DOS; it
has no particular way to know when it is getting a new sequence
of command characters. The "@" tells it to get rid of any old,
leftover junk and to start fresh. Make a habit of prefixing all
BRNDEV commands with an @ symbol. "@" also has a second
purpose, which will be covered below.
The "#" is the "execute" character. It tells BRNDEV that it has
received the whole parameter list. Only when BRNDEV sees the #
will it examine the parameter list and execute the commands.
Thus, "#" should be at the end of all BRNDEV commands; something
like "@5000 C+H-" will have no effect at all. The one exception
is that it is NOT necessary to send a "#" to execute a "@".
That is, the "@" is a live character; it is not buffered for
later execution.
It is also possible, of course, to send commands to BRNDEV from
high level languages or from assembler programs. Here's a BASIC
example:
10 OPEN "BRNDEV" FOR OUTPUT AS #1
20 PRINT #1, "@5000 C+ H-#";
30 CLOSE 1
And C (this is C86); you'd want to add some error detection:
{
FILE *burnout, *fopen();
static char command[] = "@5000 C+ H-#";
burnout = fopen("BRNDEV","w");
fwrite(command, 1, strlen(command), burnout);
fclose(burnout);
}
For an 8086 assembler example, see the source for BURNOUT.COM
(BURNOUT.ASM), which is included in the burnout library.
Basically, you have to open the device (filename=BRNDEV, fomode
0 or 2), and use function 40H (FWRITE) to write bytes to the
device using the returned handle.
Note that application programs can use the R command to force a
burnout device reset:
1000 ' SUBROUTINE TO RESET BURNOUT AND RESTORE SCREEN
1010 OPEN "BRNDEV" FOR OUTPUT AS #1
1020 PRINT #1,"@R#";
1030 CLOSE 1
1040 RETURN
Reading from BRNDEV
-------------------
Unfortunately, reading from BRNDEV is not quite as simple as
writing to it. There's no way that I can think of to do it from
the command line; you really need a program (I suppose you could
CTTY BRNDEV and then reboot when the machine went crazy [just
kidding, don't try it]). Also, there is a bug in DOS 2.x which
prevents you from using BASIC for this purpose (fixed under 3.0,
however). Under 3.0, the BASIC program would be:
10 OPEN "BRNDEV" FOR OUTPUT AS #1
20 PRINT #1, "@"; ' Note "#" not necessary here
30 CLOSE 1
40 OPEN "BRNDEV" FOR INPUT AS #1
50 BSTAT$ = INPUT$(22,1)
60 CLOSE 1
70 PRINT "Burnout status is "; BSTAT$
Note that we always write an "@" to the device before reading
its status. The @'s function is described as above, to flush
any unfinished I/O from BRNDEV's buffers. Of considerable
importance here, however, is that the @ also tells BRNDEV to
prepare for a status request. When BRNDEV sees the @, it
examines its current status and puts the data into a buffer,
from which it will be retrieved when it gets the request.
Without the preparatory @, you'll get old data.
The significance of the "22" in the INPUT$ statement is that the
BRNDEV status report is 22 characters long.
Here's a C example:
{
FILE *burnout, *fopen();
static char command[] = "@";
char status[30];
burnout = fopen("BRNDEV","rw");
fwrite(command, 1, strlen(command), burnout);
fread (status, 1, 255, burnout);
fclose(burnout);
printf("Burnout status is %s\n", status);
}
Note that we requested 255 characters. DOS, in general, will
halt a device read when it encounters a carriage return from the
input stream. BRNDEV makes a habit of sending a CR after the
last byte of the status report, so this will terminate the read
automatically; no need to worry about the true length of the
report. BASIC, however, will just keep reading until it
accumulates the requested number of characters, so you do have
to be watchful there. The same trick (requesting too many
characters) will also work in assembler programs (again, see
BURNOUT.ASM).
Now, about that bug in DOS 2.x. It turns out that DOS will mess
up if you ever request a single byte from an installed character
device, which is what BRNDEV is. (Technically: EOF is set on
the device, and you will not be able to do any further reads
unless you mess with IOCTL and explicitly reset EOF.) Thus, the
following assembler code will NOT work under 2.x:
mov cx,22 ; Loop for 22 bytes
Label:
push cx ; Save loop count
mov ah,3FH ; Read from file
mov bx,BHandle ; BRNDEV file handle (from FOPEN)
mov cx,1 ; One byte at a time
mov dx,offset buf ; Where to put the data
int 21H ; Perform read
(do something with the byte)
pop cx ; Recover loop count
loop label ; Loop till 19 bytes read
The first byte will be read OK, but no further input will be
received. You MUST read at least 2 bytes at a time.
This bug can be overcome in assembler and C by simply requesting
the full status report in one read. However, it appears that
BASIC requests only one byte at a time, even if you use
something like INPUT$(22,n). Reading the second byte then
results in a READ PAST EOF error.
Tricks
------
You can do neat stuff like waiting for the screen to burn out,
then turning it back on:
1 REM DEMO PROGRAM TO WAIT UNTIL SCREEN BLANKS
2 REM
10 OPEN "BRNDEV" FOR OUTPUT AS #1
20 OPEN "BRNDEV" FOR INPUT AS #2
30 WHILE NOT BURNED.OUT
40 PRINT #1,"@";
50 A$ = INPUT$(22,2)
60 BURNED.OUT = (MID$(A$,13,1) = "B")
70 WEND
80 BEEP: PRINT "Burned out!"
90 CLOSE 1: CLOSE 2
The 13th character of the status report, "B", will appear in the
report only when the screen is blanked.
Also, your programs can cancel burnout totally, if desired:
1 REM DEMO PROGRAM TO DISABLE BURNOUT
2 REM
10 OPEN "BRNDEV" FOR OUTPUT AS #1
20 PRINT #1,"@0#";
30 CLOSE 1
(I am not a BASIC programmer, so if any of these demo BASIC
programs are dumb, someone tell me.)
Naturally, it would be possible (and friendly) to read in the
burnout parameters, modify them while your program is running,
and restore the original parameters when you are done.
If you use Seaware's Extended Batch Language, you can even test
whether or not BRNDEV is installed from within a batch:
bat stateof BRNDEV
bat if %r = 0 type BURNOUT IS INSTALLED | goto -A1
bat type BURNOUT IS NOT INSTALLED
bat -A1
If you have a one-floppy machine, you can trick DOS and BAT into
not checking the second logical drive (and stopping the batch to
ask you to "Insert diskette for drive B") by using
bat stateof A:BRNDEV
DOS apparently doesn't care if you prefix a device name with a
drive ID.
Incompatibilities and Problems
------------------------------
I am aware of only a few problems and interactions with other
programs. In order for burnout to "see" keyboard and video
activity, active programs must use ROM BIOS (or DOS, which
itself uses BIOS) for their keyboard input and video output.
A few progams use neither; hence burnout never sees their
activity, and the screen will be irrevocably blanked. These
programs are mostly word processors; two that I know of are
XYWrite and WordVision. You must disable burnout before using
either of these ("BURNOUT 0" will do the trick). Most people do
this in a batch:
burnout 0
wv
burnout 10000
There are also problems with some communications programs if you
use software blanking. If you are performing an extended length
file transfer the screen may blank during the transfer.
Software blanking takes a little time, and communications input
can be lost while it is being accomplished. This, of course,
messes up the transfer. And Continuous Clear is even worse.
The solution is either to use hardware blanking or to disable
burnout while transfers are taking place. You MAY be able to
get away with leaving burnout enabled, but disabling Continuous
Clear (C-).
Note that the word "BRNDEV" becomes a reserved word to DOS. You
cannot name any file BRNDEV (or even BRNDEV.TXT, or whatever).
DOS won't let you do that. If you do succeed, you won't be able
to erase it. This is why the driver is stored in a file named
BURNDEV.SYS rather than BRNDEV.SYS.
Tick chart
----------
To save wear and tear on your calculator, here are some
approximate tick counts:
Minutes Count
------- -----
1 1100
2 2200
3 3275
4 4375
5 5450
6 6550
7 7650
8 8725
9 9825
10 10920
20 21850
30 32760
40 43680
50 54600
60 65520
The Usual Suspects
------------------
The author accepts no responsibility for this software
whatsoever. It might work, it might not. In particular, he
accepts no responsibility for any result of the use of the
software, even if it results in damage to your hardware.
The burnout device driver (BURNDEV.SYS) and all demonstration
programs are placed in the public domain and may be freely used
by any individual. You may not use them commercially. You may
copy and distribute the software and documentation to any other
individual, PROVIDED that you do not charge for this.
Recognized users' groups may, however, charge a small fee for
postage and materials.
I am interested in comments or suggestions on the usability of
the burnout system, especially by programmers. Contact me via
CompuServe if possible.
All software and documentation are
Copyright (c) 1985 by
Christopher J. Dunford
10057-2 WIndstream Drive
Columbia, Maryland 21044
CompuServe ID 76703,2002
